Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Semantic markdown headings #1087

Merged
merged 6 commits into from
Jun 4, 2018

Conversation

jaydenseric
Copy link
Contributor

@jaydenseric jaydenseric commented Jun 4, 2018

Fixed heading semantics

  • Previously, headings were displayed using p and strong tags. This is semantically incorrect, and would cause subheadings to display larger than headings for nested sections on platforms such as Github.
  • “Parameters”, “Properties”, and “Examples” now render as headings with a dynamic level greater than the heading they are nested under.
  • This change adds more noise to the ToC, but I suppose that is what a ToC is meant to do. Perhaps in the future a new ToC max-depth option would be nice.

Cleaner markdown generation comment

  • The old message exceeded an 80 char line width (Prettier default & best practice) by 14 chars.
  • The old instructions to update the docs by editing the source code were technically incomplete as a script somewhere would also have to be run. Explaining that the docs are generated from source code JSDoc should be sufficient; how to edit the docs can be implied. The main thing is that people know not to directly edit the generated markdown.
  • Removed the documentation.js advertisement. Curious people can learn about it by inspecting the package dev deps and scripts.

Partly fixes #1064.

- The old message exceeded an 80 char line width by 14 chars.
- By explaining that the docs are generated from source code JSDoc, how to edit the docs is implied and does not need to be explained.
- Removed documentation.js advertisment; it serves no functional purpose. Curious people will be more interested in the npm package name in dev deps rather than that a marketing name that has to be googled (documentation.js).
- Previously, headers were displayed using `p` and `strong` tags. This is semantically incorrect, and would cause subheadings to display larger than headings for nested sections on platforms such as Github.
- “Parameters”, “Properties”, and “Examples” now render as headings with a dynamic level greater than the heading they are nested under.
@tmcw
Copy link
Member

tmcw commented Jun 4, 2018

Okay - I do somewhat object to the thing being called an 'advertisement' - referring to it as documentation.js is really the only way that I can prevent the unending confusion that results from JSDoc-the-code-comment-style and JSDoc-the-documentation-generator being both named JSDoc.

@jaydenseric
Copy link
Contributor Author

jaydenseric commented Jun 4, 2018

The phrasing Generated from source code JSDoc clearly refers to JSDoc syntax in source code. I don't think we should shy from calling the syntax what it is: JSDoc. It's a little longer, but if you think it's clearer I can update it to Generated from JSDoc in source code.

Most people updating documentation are library authors who set this tooling up themselves anyway.

This can happen in another PR to unblock this one.

See documentationjs#1087 (comment).
@jaydenseric jaydenseric changed the title Semantic markdown headings and other fixes Semantic markdown headings Jun 4, 2018
@tmcw
Copy link
Member

tmcw commented Jun 4, 2018

Okay - looks like the test fixtures need another update, and this should be good to go!

For some reason I had to reinstall node_modules to get `yarn run test -u` to update them all correctly.
@coveralls
Copy link

Coverage Status

Coverage remained the same at 85.855% when pulling c536237 on jaydenseric:semantic-markdown-headings into 12c55fe on documentationjs:master.

@coveralls
Copy link

coveralls commented Jun 4, 2018

Coverage Status

Coverage remained the same at 85.855% when pulling c536237 on jaydenseric:semantic-markdown-headings into 12c55fe on documentationjs:master.

@tmcw tmcw merged commit ca6217f into documentationjs:master Jun 4, 2018
@jaydenseric jaydenseric deleted the semantic-markdown-headings branch June 5, 2018 02:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Better use of headings in Usage section
3 participants